package il.ac.biu.cs.grossmm.api.server;

/**
 * Provides API to be used by server components (objects that implement
 * <tt>Component</tt> interface). Each server component is associated with its
 * own component manager.
 */
public interface ComponentManager {

	/**
	 * Gets the named component
	 * 
	 * @param name
	 *            the component name
	 * @throws Exception
	 */
	Object getComponent(Object hint) throws Exception;

	/**
	 * Gets a component by its class. This method is a shortcut for
	 * 
	 * <pre>
	 *  (Presence) ComponentManager.getComponent(Presence.class);
	 * </pre>
	 * 
	 * @param <C>
	 * @param classHint
	 * @return the server component
	 * @throws Exception
	 */
	<C> C getByClass(Class<C> classHint) throws Exception;

	/**
	 * Release a resource previously obtained by <code>getComponent</code>
	 * 
	 * @param name
	 *            name of a released component
	 */
	void releaseComponent(Object hint);

	/**
	 * Called when a fatal error in a component occurs which prevents this
	 * component from being used by other resources. This call automatically
	 * components any resources used by this resource as well as forces any
	 * resource that uses this resource to release it.
	 * 
	 * @param resource
	 *            the resource in which the error has occured
	 * @param e
	 *            the exception which describes the error occured
	 */
	void abort(Exception e);
}
